<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="libman.css">
<TITLE>
User defined constraints
</TITLE>
</HEAD>
<BODY >
<A HREF="libman019.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="libman016.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc47">3.4</A>&nbsp;&nbsp;User defined constraints</H2><UL>
<LI><A HREF="libman020.html#toc29">Modifying variable domains</A>
<LI><A HREF="libman020.html#toc30">The IC attribute</A>
</UL>

The library <A HREF="../bips/lib/ic_kernel/index.html"><B>ic_kernel</B></A><A NAME="@default112"></A> provides a
number of facilities useful for implementing IC constraints or otherwise
extending the facilities provided by the standard IC library.<BR>
<BR>
While the <A HREF="../bips/lib/ic_kernel/index.html"><B>ic_kernel</B></A><A NAME="@default113"></A> library
exposes the structure of the IC attribute to the programmer (see below),
accessing it directly is strongly discouraged (if for no other reason,
the internals of IC may continue to evolve).
For accessing information about a variable and its domain, use the
predicates described earlier in section&nbsp;<A HREF="libman018.html#domain-query">3.2.7</A> &#8220;Variable query
predicates&#8221;.
For modifying a variable, it is particularly important to go through the
access predicates, in order to make sure that the internal state remains
consistent, that appropriate constraints are scheduled for execution as a
result of the change, etc.
The predicates available for modifying a variable are discussed in the next
section.<BR>
<BR>
<A NAME="toc29"></A>
<H3 CLASS="subsection"><A NAME="htoc48">3.4.1</A>&nbsp;&nbsp;Modifying variable domains</H3>
When using IC variables in normal code, one would typically use the
<CODE>$\=</CODE>, <CODE>$=&lt;</CODE> and <CODE>$&gt;=</CODE> family of constraints to (resp.)
remove a value, reduce the upper bound or increase the lower bound of a
variable.<BR>
<BR>
While these constraints are good for normal CSP solving, they have a
number of properties which may be less desirable when writing new
constraints. In particular, they may leave unwanted delayed goals
behind and may perform extra propagation before returning (it may be
desirable to perform all required bound updates before allowing further
propagation to occur).<BR>
<BR>
To give the constraint writer more control over such matters, special
predicates exist in the <A HREF="../bips/lib/ic_kernel/index.html"><B>ic_kernel</B></A><A NAME="@default114"></A>
module which allow direct modification of the domain without the waking of
goals (they are scheduled for execution but not actually executed).
These predicates generally accept an IC variable, a non-IC variable (which
will be constrained to make it a real IC variable) or a number.<BR>
<BR>
Full details on these predicates can be found in the reference manual; they
are listed here for completeness. Note that with the exception of
<A HREF="../bips/lib/ic_kernel/impose_bounds-3.html"><B>impose_bounds/3</B></A><A NAME="@default115"></A> none of
the goals call <A HREF="../bips/kernel/suspensions/wake-0.html"><B>wake/0</B></A><A NAME="@default116"></A>, so
the programmer is free to do so at a convenient time.
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<A HREF="../bips/lib/ic_kernel/impose_min-2.html"><B>impose_min/2</B></A><A NAME="@default117"></A><DD CLASS="dd-description">
Set the lowerbound.
<DT CLASS="dt-description"><A HREF="../bips/lib/ic_kernel/impose_max-2.html"><B>impose_max/2</B></A><A NAME="@default118"></A><DD CLASS="dd-description">
Set the upperbound.
<DT CLASS="dt-description"><A HREF="../bips/lib/ic_kernel/impose_bounds-3.html"><B>impose_bounds/3</B></A><A NAME="@default119"></A><DD CLASS="dd-description">
Sets both upper and lower bounds.
<DT CLASS="dt-description"><A HREF="../bips/lib/ic_kernel/exclude-2.html"><B>exclude/2</B></A><A NAME="@default120"></A><DD CLASS="dd-description">
Excludes an integer from an integral variable.
<DT CLASS="dt-description"><A HREF="../bips/lib/ic_kernel/exclude_range-3.html"><B>exclude_range/3</B></A><A NAME="@default121"></A><DD CLASS="dd-description">
Excludes a range of integers from an integral variable.
<DT CLASS="dt-description"><A HREF="../bips/lib/ic_kernel/set_var_type-2.html"><B>set_var_type/2</B></A><A NAME="@default122"></A><DD CLASS="dd-description">
Makes the variable be of the given type.
<DT CLASS="dt-description"><A HREF="../bips/lib/ic_kernel/set_vars_type-2.html"><B>set_vars_type/2</B></A><A NAME="@default123"></A><DD CLASS="dd-description">
Like set_var_type, but works for lists and submatrices of variables as well.
</DL>
<A NAME="toc30"></A>
<H3 CLASS="subsection"><A NAME="htoc49">3.4.2</A>&nbsp;&nbsp;The IC attribute</H3>
The IC attribute is a meta-term which is attached to all variables which
take part in IC constraints.
<A HREF="../bips/lib/ic_kernel/index.html"><B>ic_kernel</B></A><A NAME="@default124"></A> defines the IC
attribute as a structure of the following form:
<PRE CLASS="verbatim">
ic{var_type:Type,
         lo:Lo,
         hi:Hi,
         bitmap:Bitmap,
         min:SuspMin,
         max:SuspMax,
         hole:SuspHole,
         type:SuspType
        }
</PRE>
This structure holds:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>var_type</B><DD CLASS="dd-description"> The type of the variable. This defaults to 'real' but may
become 'integer' after an explicit call to <B>integers/1</B>, by being
included in an integer constraint (e.g. <B>#=</B>) or by inferences made
during constraint propagation.
<DT CLASS="dt-description"><B>lo</B><DD CLASS="dd-description"> The lower bound of the variable's domain, as a float.
<DT CLASS="dt-description"><B>hi</B><DD CLASS="dd-description"> The lower bound of the variable's domain, as a float.
<DT CLASS="dt-description"><B>bitmap</B><DD CLASS="dd-description"> Where relevant, a bitmap representation of the integer domain;
where not relevant it holds the atom <CODE>undefined</CODE>.
<DT CLASS="dt-description"><B>min</B><DD CLASS="dd-description"> Suspension list of goals to be woken on lower bound changes.
<DT CLASS="dt-description"><B>max</B><DD CLASS="dd-description"> Suspension list of goals to be woken on upper bound changes.
<DT CLASS="dt-description"><B>hole</B><DD CLASS="dd-description"> Suspension list of goals to be woken when a value is removed
from the middle of a domain. Such removals only happen for integer
variables whose domain is finite.
<DT CLASS="dt-description"><B>type</B><DD CLASS="dd-description"> Suspension list of goals to be woken when a variable's type
becomes more constrained, i.e. when a variable goes from being real to
being integer.
</DL>
The suspension list names can be used in
<A HREF="../bips/kernel/suspensions/suspend-3.html"><B>suspend/3</B></A><A NAME="@default125"></A> and
related predicates to denote an appropriate waking condition.<BR>
<BR>
The attribute of a domain variable can be accessed with the predicate
<A HREF="../bips/lib/ic_kernel/get_ic_attr-2.html"><B>get_ic_attr/2</B></A><A NAME="@default126"></A>.<BR>
<BR>
As noted above, direct access and manipulation of the attribute is
discouraged; use the access predicates instead.<BR>
<BR>
<A NAME="@default127"></A><BR>
<BR>
<HR>
<A HREF="libman019.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="libman016.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
</BODY>
</HTML>
